isp-status

Documents

isp-status API Guide

API Contract Version: 1.0.0\ Generated (UTC): 2026-02-18T16:14:49.427275Z

1. Overview

The isp-status API is the authoritative operational truth surface of the monitoring system.

It exists to:

  • Provide deterministic, machine-readable network state
  • Separate network truth from monitoring-engine integrity
  • Expose structured historical availability
  • Serve as a stable integration contract for internal systems

This API is intentionally minimal, explicit, and operationally grounded.

2. Architectural Philosophy

The system is built on clear separation of concerns:

Layer Endpoint Responsibility

Real-Time Truth /api/status Current network usability

Engine Integrity /api/health Monitoring system health

Historical Truth /api/history Structured availability history

Knowledge /docs Human-readable operational Surface documentation

Each layer answers a different question.

3. API Contract Stability

3.1 Stability Principles

  • Field names are stable once documented.
  • State codes (0, 1, 2) will not change semantic meaning.
  • Additive changes are allowed (new fields).
  • Breaking changes require versioned endpoints (e.g., /api/v2/...).
  • Silent semantic changes are prohibited.

3.2 Backward Compatibility

Existing integrations (e.g., PRTG) must continue functioning across minor releases.

3.3 Versioning Policy

Major version change required for: - Field removal - Semantic reinterpretation - Structural JSON reshaping

Minor version change allowed for: - Additional fields - Additional endpoints - Diagnostic expansion

4. /api/status --- Real-Time Network Truth

Purpose

Returns the computed usability state of each configured uplink.

Each request: - Executes live probes - Runs decision engine - Persists minute history - Returns full structured snapshot

State Codes

Code Meaning

2 UP 1 DEGRADED 0 DOWN

Minimal Check

curl -s http://HOST:PORT/api/status | jq '.uplinks[] | {name,state}'

Evidence Inspection

curl -s http://HOST:PORT/api/status | jq '
.uplinks[] |
{
  name,
  state,
  state_reason,
  iface_state,
  gw_ping_ok: (.gw_ping.ok // null),
  ping_ok: ([.ping[]|select(.ok==true)]|length),
  ping_total: (.ping|length),
  http_ok: ([.http[]|select(.ok==true)]|length),
  http_total: (.http|length)
}'

Decision Semantics

  • UP: sufficient external reachability
  • DEGRADED: partial impairment but usable
  • DOWN: no successful external validation
  • NAT uplinks may report gw_ping_ok: null

5. /api/health --- Monitoring Integrity

Purpose

Validates that the monitoring engine itself is operating correctly.

Evaluates:

  • History freshness
  • Consecutive gap size
  • SQLite subsystem status
  • Disk space
  • Memory usage
  • Process RSS
  • Permissions integrity
  • Timer/systemd behavior

Health Determination

ok: false if: - Data older than 120 seconds - Gap ≥ 5 consecutive minutes - Subsystem degraded

Example

curl -s http://HOST:PORT/api/health | jq '{ok, history_freshness}'

6. /api/history --- Historical Availability

Purpose

Provides deterministic 5-minute rollups with padding for chart stability.

Supported Ranges

  • 24h
  • 72h
  • 7d
  • 30d
  • 90d

Safe Query Example

curl -sG \
  --data-urlencode "range=24h" \
  --data-urlencode "name=Liquid (BGP01)" \
  http://HOST:PORT/api/history | jq '{range,name,summary}'

CSV Export

curl -sG \
  --data-urlencode "range=24h" \
  --data-urlencode "name=Liquid (BGP01)" \
  http://HOST:PORT/api/history.csv -o history.csv

7. Error Handling

HTTP Code Meaning

200 Success 400 Invalid parameter 403 Forbidden (LAN restriction) 404 Unknown uplink or path 500 Internal error

Errors return JSON with description where applicable.

8. Security Model

  • Designed for internal network use
  • LAN restrictions enforced for sensitive endpoints
  • No public authentication model
  • Downloads limited to approved CIDRs
  • No multi-tenant exposure

9. Performance Characteristics

  • /api/status executes live probes (active workload)
  • /api/health lightweight
  • /api/history SQLite read + padding
  • Designed for polling intervals ≥ 30 seconds
  • Not intended for high-frequency scraping

10. Integration Guidance

  • Poll /api/status
  • Extract .uplinks[].state
  • Map states to monitoring alarms
  • Use /api/history for SLA reporting
  • Use /api/health as meta-monitor

Important

Always use URL encoding for uplink names with spaces:

curl -G --data-urlencode ...

11. Deprecation Policy

If an endpoint must be replaced:

  1. Introduce new versioned endpoint
  2. Maintain old endpoint for transition period
  3. Document deprecation timeline
  4. Remove only after controlled migration

12. Operational Workflow

  1. Validate network state → /api/status
  2. Validate monitoring engine → /api/health
  3. Investigate trends → /api/history
  4. Review design intent → /docs

13. Lessons Learned

  • Separate monitoring truth from network truth
  • Never infer availability from UI alone
  • Deterministic time buckets prevent visual misinterpretation
  • URL encoding errors can mimic API failure

14. Design Principle

The API exists so that:

  • Dashboards are views, not truth
  • Evidence precedes interpretation
  • Integrations are deterministic
  • Monitoring is observable